home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Complementary Applications 2004 February / SGI IRIX 6.5 Complementary Applications 2004 February.iso / dist / cde.idb / usr / dt / share / examples / dthelp / help / helpdemo.htg.z / helpdemo.htg
Encoding:
Text File  |  2003-11-18  |  23.8 KB  |  874 lines
  1. <!-- helpdemo.htg -->
  2.  
  3. <!-- Copyright 2000, Silicon Graphics, Inc. -->
  4. <!-- ALL RIGHTS RESERVED -->
  5.  
  6. <!-- UNPUBLISHED Rights reserved under the copyright laws of the United -->
  7. <!-- States.   Use of a copyright notice is precautionary only and does not -->
  8. <!-- imply publication or disclosure. -->
  9.  
  10. <!-- U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND: -->
  11. <!-- Use, duplication or disclosure by the Government is subject to restrictions -->
  12. <!-- as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights -->
  13. <!-- in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or -->
  14. <!-- in similar or successor clauses in the FAR, or the DOD or NASA FAR -->
  15. <!-- Supplement.  Contractor/manufacturer is Silicon Graphics, Inc., -->
  16. <!-- 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311. -->
  17.  
  18. <!-- THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY -->
  19. <!-- INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION, -->
  20. <!-- DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY -->
  21. <!-- PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON -->
  22. <!-- GRAPHICS, INC.  -->
  23.  
  24. <!entity HELPlogo         FILE "helpShelf.pm">
  25. <!entity SnapshotIcon        FILE "Snapshot.xwd">
  26.  
  27. <!entity SoundIcon              FILE  "speaker.pm">
  28. <!entity head-down        FILE "head-down.xwd">
  29. <!entity sunset            FILE "sunset.xwd">
  30. <!entity tribe            FILE "tribe.xwd">
  31. <!entity dead-jim        FILE "deadjim.xwd">
  32. <!entity computer-bee        FILE "bee.xwd">
  33.  
  34. <!entity bugs-bunny        FILE "bugs.bunny.xwd">
  35.  
  36. <!entity rooster        FILE "rooster.xpm">
  37. <!entity clouds            FILE "clouds.xpm">
  38.  
  39. <!entity space-shuttle        FILE "shuttle2.xwd">
  40. <!entity integral               FILE "integral.bm">
  41. <!entity snapshot        FILE "Snapshot.bm">
  42.  
  43. <!entity clock                  FILE "clock.xwd">
  44. <!entity xload            FILE "xload.xwd">
  45. <!entity ApplicationWithHelp    FILE "AppWithHelp.xwd">
  46. <!entity QuickHelpModel         FILE "QuickHelp.xwd">
  47. <!entity GeneralHelpModel    FILE "GeneralHelp.xwd">
  48.  
  49.  
  50.  
  51. <!entity HELPICONENT FILE "helpicon.ent"> 
  52.         &HELPICONENT;
  53. <!entity HELPLANGENT FILE "helplang.ent"> 
  54.         &HELPLANGENT;
  55. <!entity HELPCHARENT FILE "helpchar.ent">
  56.         &HELPCHARENT;
  57.  
  58. <metainfo>
  59.  
  60.   <title>CDE Help System Demo Volume
  61.  
  62.   <copyright>
  63.   <image><term nogloss|Common Desktop Environment (CDE)|
  64.   Copyright © 1993, 1994 Hewlett-Packard Company
  65.   Copyright © 1993, 1994 International Business Machines Corp.
  66.   Copyright © 1993, 1994 Novell, Inc.
  67.   Copyright © 1993, 1994 Sun Microsystems, Inc.
  68.   <\image>
  69.  
  70.   <abstract>
  71.      Demonstration help volume for the CDE Help System.
  72.   <\abstract>
  73.  
  74.  
  75.  
  76. <!-- CLASSESDEF -->
  77.  
  78. <otherfront id=CLASSESDEF><head>Widget Class
  79.  
  80. A type of widget.  A widget's !!class!! determines what methods will be
  81. called for it and what instance variables it has.
  82.  
  83. <procedure>See Also
  84.  
  85.  
  86. <list bullet tight>
  87.  * <xref SUBCLASSESDEF>
  88.  * <xref WIDGETDEF>
  89. <\list>
  90.  
  91. <!-- SUBCLASSESDEF -->
  92.  
  93. <otherfront id=SUBCLASSESDEF><head>Widget Subclass
  94.  
  95. A more specific class, used to create related widget objects.  A widget
  96. !!subclass!! has its own features plus many of the features of its
  97. superclasses.
  98.  
  99.  
  100. <procedure>See Also
  101.  
  102. <list bullet tight>
  103.  * <xref CLASSESDEF>
  104.  * <xref WIDGETDEF>
  105. <\list>
  106.  
  107. <!-- WIDGETDEF -->
  108.  
  109. <otherfront id=WIDGETDEF><head>Widget
  110.  
  111. An individual component used within a graphical user interface.
  112. Widgets are like "building blocks" -- push buttons, scroll bars, data
  113. fields -- used to build application interfaces.
  114.  
  115. <procedure>See Also
  116.  
  117. <list bullet tight>
  118.  * <xref CLASSESDEF>
  119.  * <xref SUBCLASSESDEF>
  120. <\list>
  121.  
  122.  
  123.  
  124.  
  125.  
  126. <otherfront id=gifted-topic><head>He's dead, Jim!
  127.  
  128. <figure nonumber 
  129. entity=dead-jim ghyperlink="dtaction Play sounds/deadjim.snd&" glinktype=Execute>
  130. <\figure>
  131.  
  132. <otherfront id=head-down-topic><head>Nope, nothing in here.
  133.  
  134.  
  135. <figure nonumber entity=head-down
  136. ghyperlink="dtaction Play sounds/clunk.snd &" glinktype=Execute>
  137. <\figure>
  138.  
  139.  
  140. <otherfront id=sunset-topic><head>Online!
  141.  
  142.  
  143. <figure nonumber
  144. entity=sunset ghyperlink="dtaction Play sounds/haleluja.snd &" glinktype=Execute>
  145. <\figure>
  146.  
  147.  
  148. <otherfront id=tribe-topic><head>Learning products cost too much?
  149.  
  150. <figure nonumber
  151. entity=tribe ghyperlink="dtaction Play sounds/tarzan.snd &" glinktype=Execute>
  152. <\figure>
  153.  
  154.  
  155. <otherfront id=whats-up-doc-topic><head>What's up?
  156.  
  157. <figure nonumber entity=bugs-bunny ghyperlink="dtaction Play sounds/whatsup.snd &" glinktype=Execute>
  158. <\figure>
  159.  
  160. <!--
  161.  
  162. <esc>
  163. <figure file graphics/whatsup.xwd link "dtaction Play sounds/whatsup.snd &" typelink 3>
  164. </figure>
  165. <\esc>
  166.  
  167. -->
  168.  
  169. <\metainfo>
  170.  
  171.  
  172. <hometopic>The CDE Help System
  173.  
  174. <p indent gentity=HELPlogo gposition=left>
  175. <emph>Welcome to a self-paced demonstration of the
  176. CDE Help System!<\emph> 
  177.  
  178.  
  179. <newline>What better way to learn about a hypermedia system, than by using the
  180. system itself.  This demo lets you explore information and 
  181. capabilities about CDE Help according to your interests.
  182.  
  183.  
  184.  
  185.                 <idx|getting started|
  186. To get started, choose one of the hyperlinks below (they're underlined):
  187.  
  188. <list bullet tight>
  189.  * <xref overview>
  190.  * <xref features>
  191.  * <xref design>
  192. <\list>
  193.  
  194. <note>
  195. This help volume serves as a self-paced demonstration of the CDE Help System, 
  196. as well as supports the various help entry points used within the 
  197. ``dthelpdemo'' sample program. ``dthelpdemo'' is sample OSF/Motif client 
  198. intented to show how the CDE Help System can be used.  The source code
  199. for both the ``dthelpdemo'' client as well as this help volume are
  200. present on your system.
  201. <\note>
  202.  
  203.  
  204.  
  205. <!-- FEATURES -->
  206.  
  207. <s1 id=features>A Self-Guided Tour
  208.                 <idx|touring CDE Help|
  209.  
  210. This tour demonstrate the major features of the CDE Help System.  You may
  211. explore them in any order.
  212.  
  213. While exploring, to return to a previous topic, choose the Backtrack
  214. command button.  To return to the top-level topic, choose Contents.
  215.  
  216. The indented list at the top of the help window tells you where you are in
  217. the topic hierarchy and lists the sutopics for the current topic.  You can
  218. go directly to any topic in the path by selecting its title.
  219.  
  220.  
  221. <!-- OVERVIEW -->
  222.  
  223. <list bullet tight>
  224.  * <xref HYPERTEXT>
  225.  * <xref DEFINITIONS>
  226.  * <xref GRAPHICS>
  227.  * <xref AUDIO>
  228.  * <xref COMMANDS>
  229.  * <xref COMMUNICATION>
  230. <\list>
  231.  
  232. <s2 id=OVERVIEW>General Overview
  233.  
  234. CDE Help is an online help system, primarily intended for OSF/Motif
  235. applications. The following sections provide a summary of major CDE Help
  236. features.  (For more details, refer to "<xref DESIGN>.")
  237.  
  238. <otherhead>Hyperlinks
  239.  
  240. Hyperlinks are the key feature in a hypermedia system.
  241. CDE Help supports four types of hyperlinks:
  242.  
  243. <list bullet>
  244.  
  245. * <emph>Standard hypertext jumps<\emph> immediately move the reader to
  246. a different location within the online information.  By default, these
  247. types of jumps replace the contents of the existing window.  However,
  248. the author may specify jumps that should be displayed in a "new view."
  249. (For more detail, refer to "<xref HYPERTEXT>.")
  250.  
  251. * <emph>Definition links<\emph> temporarily show the definition of a key
  252. word or phrase.  Although intended for keyword-to-glossary lookup,
  253. definition links have many other useful applications. (For an example,
  254. refer to "<link hyperlink="Intromgr _HOMETOPIC" JumpNewView>Introducing the CDE Desktop.<\link>.")
  255.  
  256. * <emph>Command links<\emph> execute an author-defined command to
  257. invoke an action beyond the domain of the help system.  Any shell
  258. command can be executed, so this feature is really the "open door" to
  259. the outside world for CDE Help authors. (To try examples, refer to 
  260. "<xref COMMANDS>.")
  261.  
  262. * <emph>Application-defined links<\emph> (To try some examples, refer
  263. to "<xref COMMUNICATION>.")
  264.  
  265. <\list>
  266.  
  267. <otherhead>Embedded Graphics
  268.  
  269. CDE Help supports the following graphics formats.  To view samples
  270. of a few of these formats, refer to "<xref GRAPHICS>."
  271.  
  272. <list bullet>
  273.  
  274. * !!X Window Dump!! (xwd) color graphics.  This format is
  275. created using the standard <computer>xwd<\computer> utility program.
  276. Many popular graphics tools for the X Window System also support this
  277. format.
  278.  
  279. * !!X Pixmap!! (xpm) color graphics.  This is an emerging
  280. standard format for multicolor icons.
  281.  
  282. * <emph>X Bitmap<\emph> (bitmap) two-tone graphics.  The foreground
  283. and background of these images tracks the foreground and background
  284. used to display text in the display area.  This format can be created
  285. and edited using the standard <computer> bitmap<\computer> utility
  286. program.
  287.  
  288. * <emph>TIFF<\emph> (tagged image file format) black and white and
  289. greyscale graphics.  This is perhaps the most common format in the
  290. personal computer graphics industry.
  291.  
  292. <\list>
  293.  
  294.  
  295. <otherhead>Interactive Keyword Index
  296.  
  297. CDE Help's keyword index functions much like the index in a book,
  298. listing words the author marked as important.  Unlike the index in a book,
  299. this online index accelerates the reader's ability to jump to references
  300. because each word or phrase is a link to the location (or list of
  301. locations) where it is used.
  302.  
  303.  
  304. <otherhead>Help Registration
  305.  
  306. When an application is installed, it may install its help files in any
  307. location.  Optionally, applications can participate in a "registration"
  308. process that enables two important features for online help:
  309.  
  310. <list bullet>
  311.  
  312. * <emph>Cross-application links<\emph> that allow hyperlinks to jump
  313. from one application's help to another's.
  314.  
  315. * <emph>System-wide access to help<\emph> provided by the <link
  316. hyperlink="browser _HOMETOPIC" JumpNewView>CDE Help Manager<\link>.
  317.  
  318. <\list>
  319.  
  320. <note>
  321. See the <link dtappintegrate man>dtappintegrate Man Page<\link>
  322. for specific information on registration of application help volumes.
  323. <\note>
  324. <!-- HYPERTEXT -->
  325.  
  326. <s2 id=HYPERTEXT>Hyperlinks for Navigation
  327.  
  328. The "hyper" in hypermedia is what separates hypermedia systems
  329. from online documentation systems.  Unlike books that have a linear
  330. organization, hyperlinks let authors create many different, nonlinear
  331. organizations, including "webs," "trees," "circles," and "chains."
  332.  
  333. In CDE Help, the basis for all organizations is a hierarchy.
  334. However, authors can augment the structure by creating links between
  335. related topics that are in different branches of the hierarchy.
  336.  
  337. <otherhead>Simple Jumps (Same Window)
  338.  
  339. Most hyperlinks are simple jumps within the same application help.  These
  340. simple jumps reuse the same window, overwriting the previous topic with
  341. each jump.
  342.  
  343. <otherhead>Jumping to a New Window
  344.  
  345. When an author creates a new link, she can specify that the link should
  346. open a new help window.  The application is responsible for creating and
  347. managing the new window.
  348.  
  349. <p gentity=SnapshotIcon glinktype=JumpNewView ghyperlink=HYPERTEXT>
  350. For example, this camera icon is a hyperlink to this topic on
  351. hypertext.  However this link specifies that a new window is desired.
  352. Effectively, this link takes a "snapshot" of this window.  You may use
  353. this snapshot link to create as many demo windows as you want.  The demo
  354. will continue to run until you close the last one.
  355.  
  356. <otherhead>Knowing Where You Are
  357.  
  358. Near the top of the general help window is an indented list of
  359. topic titles.  This list represents your current position (highlighted entry)
  360. with respect to its related topics.
  361.  
  362. You can go directly to any of the related topics in the list by selecting its
  363. title.
  364.  
  365. <otherhead>Knowing Where You've Been
  366.  
  367. CDE Help keeps track of each topic you've viewed in each help
  368. window.  To go back to previous topics, you can:
  369.  
  370. <list bullet>
  371.  
  372. * Choose Backtrack from the Navigate menu or from the pop-up menu in the
  373.   dipslay area to immediately go back to the previous topic.
  374.  
  375. * Choose History from the Search menu to display a list of all the topics
  376.   you've viewed. To return to a topic, select its title in the list.
  377.  
  378. <\list>
  379.  
  380.  
  381. <!-- DEFINITIONS -->
  382.  
  383. <s2 id=DEFINITIONS>Pop-Up Definition Links
  384.  
  385. A special class of hyperlink is provided for temporarily displaying
  386. "elaborative" information.  Most frequently, this feature is used to
  387. display the glossary definition for a key word or phrase.
  388.  
  389. For example, the following paragraph has three definition links.
  390.  
  391. <p indent>OSF/Motif graphical user interfaces are constructed using <link
  392. WIDGETDEF Definition>widgets<\link>.  Widgets are organized by form and
  393. function into <link CLASSESDEF Definition>classes<\link> and <link
  394. SUBCLASSESDEF Definition>subclasses<\link>.
  395.  
  396. The use of definition links is not limited to defining key words and
  397. phrases.  For instance, you could use this feature to provide a <link
  398. hyperlink="Intromgr quick-start" JumpNewView>visual overview<\link> of the
  399. application.
  400.  
  401.  
  402.  
  403.  
  404.  
  405. <!-- GRAPHICS -->
  406.  
  407. <s2 id=GRAPHICS>A Graphics Sampler
  408.  
  409. The following images demonstrated the diverse capabilities of CDE Help's
  410. graphics support.  Some of these images are oversized -- you 
  411. may want to resize the window to get a better view.
  412.             <idx|Graphics Sampler|
  413. <!--
  414. <esc>
  415. <figure file graphics/color.xwd>
  416. </figure>
  417. <newline>
  418. <newline>
  419. <\esc>
  420.  
  421. <esc>
  422. <figure file graphics/hutlogo.xwd>
  423. </figure>
  424. <newline>
  425. <newline>
  426. <\esc>
  427. -->
  428.  
  429. <figure nonumber entity=computer-bee>
  430. <\figure>
  431.  
  432. <otherhead>We Do Bitmaps!
  433.  
  434. <figure nonumber entity=integral>
  435. <\figure>
  436.  
  437. <!--
  438. <esc>
  439. <figure file graphics/libAnne.bm>
  440. </figure>
  441. <newline>
  442. <newline>
  443. <\esc>
  444. -->
  445.  
  446. <!--
  447. <esc>
  448. <figure file graphics/hplogo.bm>
  449. </figure>
  450. <newline>
  451. <newline>
  452. <\esc>
  453. -->
  454.  
  455. <figure nonumber entity=snapshot>
  456. <\figure>
  457.  
  458. <otherhead>We Do Grayscale!
  459.  
  460. <figure nonumber entity=space-shuttle>
  461. <\figure>
  462.  
  463.  
  464. <s2 id=Audio>An Audio Sampler
  465.  
  466.             <idx|Audio Sampler|
  467. <figure nonumber
  468. entity=rooster ghyperlink="dtaction Play sounds/rooster.snd &" glinktype=Execute>
  469. <\figure>
  470.  
  471.  
  472. <figure nonumber
  473. entity=clouds ghyperlink="dtaction Play sounds/thunder.snd &" glinktype=Execute>
  474. <\figure>
  475.  
  476. <otherhead>Pop-Up Windows With Graphical Audio Links
  477.  
  478.  
  479. <list bullet>
  480.  
  481.  * <link whats-up-doc-topic Definition>Whats up?<\link>
  482.  
  483.  * <link gifted-topic Definition>Our customer, after getting too many
  484.    manuals ...<\link>
  485.  
  486. <!--
  487.  * <link head-down-topic Definition>Our competitors ...<\link>
  488. -->
  489.  
  490.  * <link sunset-topic Definition>I found it ...<\link>
  491.  
  492. <!--
  493.  * <link tribe-topic Definition>A coffee talk ...<\link>
  494. -->
  495.  
  496. <\list>
  497.  
  498.  
  499. <otherhead>Some Text-Based Audio Links
  500.  
  501. <list plain loose>
  502.  
  503.  * <link hyperlink="dtaction Play sounds/monkey.snd &" Execute>
  504.    Monkey<graphic entity=SoundIcon>
  505.    <\link>
  506.  
  507.  * <link hyperlink="dtaction Play sounds/chord.snd &" Execute>
  508.    Pleasant Chord<graphic entity=SoundIcon>
  509.    <\link>
  510.  
  511.  * <link hyperlink="dtaction Play sounds/hal2.snd &" Execute>
  512.    Hal 9000 <graphic entity=SoundIcon>
  513.    <\link>
  514.  
  515.  * <link hyperlink="dtaction Play sounds/attack.snd &" Execute>
  516.    Prepare to attack!  <graphic entity=SoundIcon>
  517.    <\link>
  518.  
  519.  * <link hyperlink="dtaction Play sounds/beback.snd &" Execute>
  520.    I'll be back!<graphic entity=SoundIcon>
  521.    <\link>
  522. <\list>
  523.  
  524. <!-- COMMANDS -->
  525.  
  526. <s2 id=COMMANDS>Executing Commands
  527.             <idx|Command execution|
  528. Each of the following icons is a hyperlink assigned to a particular
  529. system command.  If the program in the command is installed on your
  530. system, clicking the icon will invoke it.
  531.  
  532. <p gentity=clock ghyperlink="DtHelpExecAlias xclockAlias" glinktype=Execute>This
  533. icon starts the ``xclock'' program if it is
  534. installed on your system, and in your PATH.
  535.  
  536. <p gentity=xload ghyperlink="DtHelpExecAlias xloadAlias" glinktype=Execute>This
  537. icon starts the ``xload'' program if it is installed on your
  538. system, and in your PATH.
  539.  
  540. Command links do not have to be graphics.  For example, this link
  541. executes the <link EXECUTE hyperlink="DtHelpExecAlias dtCalcAlias">CDE 
  542. Calculator<\link> program (if it is installed on your system).
  543.  
  544. <note>
  545. The above Execute examples take advantage of Execution Aliases in the
  546. hyperlinks. When execution alises are defined in the help volume, and 
  547. supported in the hosting client, they execute directly when selected by the 
  548. user. 
  549.  
  550. To learn more general information about supporting execution hyperlinks and
  551. aliases, refer to the <book|CDE Author's and Programmer's Guide|.
  552.  
  553. <\note>
  554.  
  555.  
  556.  
  557. <!-- COMMUNICATION -->
  558.  
  559. <s2 id=COMMUNICATION>Two-Way Communication
  560.             <idx|Two way communication|
  561. A help system that is tightly coupled with an application has more
  562. potential for presenting relevant, context-sensitive information.  The
  563. architecture of the ...
  564.  
  565. <otherhead>Help System Controlling the Application
  566.  
  567. Since CDE Help is intended for use in OSF/Motif-based applications, it takes
  568. advantage of the !!callback!!  mechanism used by all other user interface
  569. components.  Help callbacks notify the application when certain events
  570. occur within a help window.
  571.  
  572. Perhaps the most powerful use of help callbacks is the use of
  573. !!application-defined links!!.  These are link types invented by the
  574. application developer that can have any meaning.
  575.  
  576.  
  577. For example, a developer may want to create a special type of link to
  578. play video clips.  Each time the user selects one of these links, the
  579. application is notified so it can do whatever is necessary to play the
  580. appropriate video.
  581.  
  582. <xref controlTestId>
  583.  
  584. <otherhead>Application Controlling the Help System
  585.  
  586. As a toolkit, all CDE Help facilites are under control of the
  587. application.  All help windows are transient windows of the
  588. application.  The application can control the number of help windows,
  589. the color schemes used within them and other options provided by the
  590. CDE Help libraries.
  591.  
  592.  
  593. <s3 id=controlTestId> Sample Application Defined Links
  594.  
  595. The following collection of hypertext links demonstrate how the CDE Help 
  596. System can control the hosting application.  These links are authored
  597. as <emph>AppDefined<\emph> links, and require special support in the hosting
  598. client
  599.  
  600. <note>
  601. These example !!application-defined!! links are supported by the ``dthelpdemo''
  602. program. (If you view this help volume with another application, such as
  603. dthelpview, the links are ignored.)
  604. <\note>
  605.  
  606. <otherhead>Controlling <emph>YOUR<\emph> client:
  607.  
  608. <list bullet>
  609. * <link hyperlink="100" type=AppDefined> Move dthelpdemo's window<\link>
  610. * <link hyperlink="101" type=AppDefined> Resize dthelpdemo's window<\link>
  611. <\list>
  612.  
  613.  
  614.  
  615. <!-- design -->
  616.  
  617. <s1 id=design>The CDE Help System Design
  618.  
  619.  
  620.  
  621. <!-- MODEL -->
  622.  
  623. <list bullet tight>
  624.  * <xref MODEL>
  625.  * <xref TOOLKIT>
  626.  * <xref API>
  627.  * <xref HELPTAG>
  628. <\list>
  629.  
  630. <s2 id=MODEL>The CDE Help System Use Model
  631.                 <idx|use model|
  632.                 <idx|prime directive|
  633.  
  634. The overriding principle for providing online help is:
  635.  
  636. <p indent>!!Get the user back on task as quickly and successfully as
  637. possible.!!
  638.  
  639. To fulfill this "prime directive," online help must be easily accessible
  640. within whatever applications the user has chosen to accomplish the task.
  641.  
  642. The CDE Help System is cast in a supporting roll.  That is,
  643. the help system's job is to function as part of the application with
  644. the purpose of making the user successful with the rest of the
  645. application.
  646.  
  647. <figure nonumber entity=ApplicationWithHelp>
  648. <\figure>
  649.  
  650. The idea of keeping the help system tightly coupled with the application
  651. improves the user's <emph>perceived proximity<\emph>.  User are more likely
  652. to be successful and productive if they feel like devations to get help
  653. don't take them far from the application.
  654.  
  655. CDE Help supports two types of <emph> entry
  656. points<\emph> into online help:
  657.  
  658. <list bullet>
  659.  
  660. * <link QUICKHELP>Quick help<\link> presents a focussed node of
  661. information for a given context.
  662.  
  663. * <link GENERALHELP>General help<\link> presents navigable information
  664. that the user can explore.
  665.  
  666. <\list>
  667.  
  668.  
  669. <!-- QUICKHELP -->
  670.  
  671. <s3 id=QUICKHELP>Quick Help
  672.  
  673. Quick help information is optimized -- by writing style and 
  674. organization -- to get the user back on task with minimal interruption.
  675.  
  676. <figure entity=QuickHelpModel>
  677. <\figure>
  678.  
  679. Quick help has a high level of context sensitivity and contains very
  680. specific information.  By design, the content and presentation of
  681. quick help information should <emph>not<\emph> encourage the user to
  682. "explore."
  683.  
  684. So, what if a quick help entry point doesn't fill the user's need?
  685. <emph>Progressive disclosure<\emph> sequences are designed to maintain
  686. a sense of proximity, while exploring an author-constrained path of
  687. nodes that incrementally provide more information for the given
  688. context.  (This concept is sometimes called "progressive revelation"
  689. or "progressively-more-help.")
  690.  
  691. Typical uses of quick help include:
  692.  
  693. <list bullet>
  694.  
  695. * Messages (errors, status, etc.).
  696.  
  697. * Context-sensitive help (invoked with F1 key or Help command button).
  698.  
  699. * Each step in a constrained progressive disclosure sequence.
  700.  
  701. * Item help.
  702.  
  703. * Application copyright and version.
  704.  
  705. * Simple help on help.
  706.  
  707. <\list>
  708.  
  709.  
  710. <!-- GENERALHELP -->
  711.  
  712. <s3 id=GENERALHELP>General Help
  713.  
  714. General help information is anything that isn't quick help.  Usually,
  715. general help is intended to be explored (such as this demo).
  716.  
  717. <figure nonumber entity=GeneralHelpModel>
  718. <\figure>
  719.  
  720. Typical uses of general help include:
  721.  
  722. <list bullet>
  723.  
  724. * Application overview.
  725.  
  726. * A follow-up to quick help -- that is, when quick help isn't enough.
  727.  
  728. * Application tutorials.
  729.  
  730. * Application training modules.
  731.  
  732. * Complete help on help (when quick help on help isn't enough).
  733.  
  734. <\list>
  735.  
  736.  
  737. <!-- TOOLKIT -->
  738.  
  739. <s2 id=TOOLKIT>The Toolkit Architecture
  740.  
  741. Application developers add help components to their
  742. software just as they add any other window.  The CDE Help
  743. programmer's toolkit defines new widget classes for the various help
  744. windows.  There are many advantages to this toolkit architecture:
  745.  
  746. <list bullet>
  747.  
  748. * There's no dependency on a separate help server process -- the 
  749.   "help system" is part of the application.
  750.  
  751. * Response time is dramatically faster.
  752.  
  753. * Memory usage is significantly less (which increases overall system
  754. performance).
  755.  
  756. * User's perceive help to be part of the application, making it seem
  757. like less of a deviation to ask for help.
  758.  
  759. * There's no need for an inter-process communication (IPC) mechanism.
  760. The application interacts with CDE Help components just as it does
  761. with all other user interface components.
  762.  
  763. * There's no new programming paradigm -- all CDE Help
  764.   components are accessed using the same object-oriented
  765.   interface used for OSF/Motif (via the Xt Intrinsics and convenience
  766.   functions).
  767.  
  768. <\list>
  769.  
  770. Since the CDE Help toolkit is based exclusively on standards (ANSI
  771. C, Xlib, Xt Intrinsics, and OSF/Motif), it is as portable as any OSF/Motif
  772. application can be.
  773.  
  774.  
  775.  
  776. <!-- HELPTAG -->
  777.  
  778. <s2 id=API>CDE Help API Summary 
  779.  
  780.         <idx|API summary|
  781.  
  782. The CDE Help System's Application Programmers Interface (API) includes the
  783. following functions:
  784.  
  785. <list bullet>
  786.  * Functions for creating and working with help dialogs:
  787.  
  788. <list plain tight>
  789.  * <link DtHelpDialog man>DtHelpDialog()<\link>
  790.  * <link DtHelpQuickDialog man>DtHelpQuickDialog()<\link>
  791.  * <link DtCreateHelpDialog man>DtCreateHelpDialog()<\link>
  792.  * <link DtCreateHelpQuickDialog man>DtCreateHelpQuickDialog()<\link>
  793.  * <link DtHelpQuickDialogGetChild man>DtHelpQuickDialogGetChild()<\link>
  794. <\list>
  795.  
  796.  * Function for implementing item help mode:
  797.  
  798. <list plain tight>
  799.  * <link DtHelpReturnSelectedWidgetId man>DtHelpReturnSelectedWidgetId()<\link>
  800. <\list>
  801.  
  802.  * Function for specifying the message catalog for the Xvh library:
  803.  
  804.  
  805. <list plain tight>
  806.  * <link DtHelpSetCatalogName man>DtHelpSetCatalogName()<\link>
  807. <\list>
  808. <\list>
  809.  
  810.  
  811.  
  812. <!-- HELPTAG -->
  813.  
  814. <s2 id=HELPTAG>Authoring with HelpTag
  815.  
  816. Authoring for CDE Help is based on the HelpTag markup language and
  817. accompanying software.  HelpTag is based on the SMGL standard (ISO
  818. 8879).
  819.  
  820.  
  821. <otherhead>The HelpTag Markup Language
  822.  
  823. Online help is written in ordinary text files. You use special codes, or tags to
  824. markup elements within the information.  The tags form a markup language called
  825. CDE HelpTag.
  826.  
  827. The CDE HelpTag markup language defines a hierarchy of elements that define
  828. high-level elements such as chapters, sections, and subsections, and low-level
  829. elements such as paragraphs, lists, and emphasized words.
  830.  
  831. To learn more general information about authoring with CDE HelpTag, refer to 
  832. the <book|CDE Author's and Programmer's Guide|.
  833.  
  834.  
  835. <otherhead>The HelpTag Software
  836.  
  837. The HelpTag software is responsible for converting the author's files
  838. into the run-time help files that are shipped with the application.
  839. The software is invoked with a command like this:
  840.  
  841. <ex>dthelptag %%basename%%.htg<\ex>
  842.  
  843. A  run-time help file is generated.  If the application that
  844. the help is intended for is ready to use, the help volume can be tested
  845. immediately.
  846.  
  847. If the application is not ready, or the help is not associated with a
  848. particular application, it can be viewed using the <book|dthelpview| preview
  849. client.
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.